MULTICS TECHNICAL BULLETIN MTB-120 


TO: Distribution 
FROM: J. W. Gintell 
DATE: September 30, 1974 


SUBJECT: New probe command 


Attached is the documentation on the new probe command. Any 
comments may be submitted to Jeff Broughton or John Gintell. 


Multics Project internal working documentation. Not to be reproduced 
or distributed outside the Multics Project. 
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Command 
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Name: probe, pb 


The probe command is a symbolic debugging aid that allows 
the user. to interactively examine the state of his pvronrram. 
Commands are provided to display and alter the value ang 
variables, to interrupt a running program at a varticular 
statement by use of breakpoints, to list the source program, to 
examine the stack of block invocations, and to invoke external 
subroutines and functions. 


In order to debug a program with probe, the program must 
have a standard symbol table that contains information about 
variables defined in the program.and a statement man givina the 
correspondence between source statements and object code. A 
symbol table and statement map is produced by the PL/I and 
Fortran compilers if the te—table* option is specified. (A 
program may also be compiled with the Nebrief_table" option 
which will produce only the statement map and disable the 
ape es. to reference variables.) 


To store certain information about orograms being debuoned, 
probe uses a segment in the user’s home directory called 
Username.probe where Username is the user’s personid. This 
segment is created automatically when needed. 


Introduction: 


The primary use of probe is to examine a proaram whose 
execution has been suspended. This. can occur in one of several 
WaYSe 


First, execution may be interrupted as a result of an error 
occurring. in the program such as zerodivide or overflow. After 
an error message is printed on the user’s console, and a new 
command level entered, probe may be called and commands issued 
to it to identify the cause of the error. 


| Second, the user can, as always, stop a run-away pbrooram by 
"quitting". 


Third, the user may designate, by use of probe’s break 
commands, statements on which the program is to stop and directly 
enter probe. A list of commands associated with the break 
would then be executed automatically. These commands could vorint 
a variable, tell what line was just executed, or cause probe to 
read additional commands from the console. In this way, the user 
can follow the progress of his proaram before an error occurs. 
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In all of the cases above, an active prooram has. been 
suspended. This means that variables of all storage classes, in 
particular automatic, exist and may be displayed. Probe may 
also be used to examine a non-active program -- one that has 
never been run or that has completed. Used in this manner, probe 
can be used to look at static variables, and the program source, 
though the most common use is to set breaks before actually 
running the program. 


Probe maintains three "pointers" that can affect the 
execution of many commands. They are: the source pointer which 
marks a particular source program statement as the "current 
statement" and the program as the "current program"; the symbol 
pointer which indicates the "current block" and generation of 
storage (i.e. stack frame) in which to evaluate symbolic 
references to variables}3 and the cantrol pointer which 
designates the statement at which control was suspended in the 
procedure of interest. 


Usage: 
probe —<procedure>= 


where <procedure> is an optional argument aiving the name of an 
entry which the user is interested in. If the procedure is 
active, the control and source pointers will be set to the last 
statement executed, and the symbol pointer will be set to the 
most recent invocation of the procedure. If it is not active, 
then the control and source pointers will be set to point to the 
entrv statement, and the symbol pointer will desiaqnate the 
outermost block of the procedure. 


If a <procedure> is not specified, probe will check if an 
error or auit has occurred and, by default, use the procedure 
that was executing. The pointers will be set as if the user had 
specified it explicitly. If no error has occurred, then probe 
will print a message and return. 


When probe is entered as the result of executing a procedure 
with a breakpoint set in it, the control and source pointers are 
set to the statement on which the break was set, and the symbol 
pointer to the block that contains that statement. 


In general, after an error, quit, or break, things will be 
set up by default much as one would expect. The user should, 
however, explicitly name a <procedure> when he is interested in 
working with a non-active one. 
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Once probe has been entered, the user may issue commands to 
it in order to examine his program... 


Command Syntax: 


The command language recognizes three constructs: simple 
commands, command lists, and conditional commands. Loosely, a 
simple command is a basic probe request, and a command list is a 
list of commands separated by semi-colons (or newlines). A 
conditional command is a simple command or list (surrounded bv 
parentheses) prefixed by a conditional predicate controlling when 
the request is to be performed. Examples follow in the next 
section. 


In the discussion of commands that follows, meta-language © 
symbols will be used for certain constructs (e.g. <expression>). 
Their meaning should be apparent from context and from examples 
given. A complete discussion will be found later in this 
writeup. 
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Basic Commands 


print {<expression>:<cross section>} 


Output on the console the value of <expression>. The print 
request allows the user to display the value of variables, 
builtin functions such as addr and octal, and the value returned 
by an external function. 


orint var 

print 0 => a.b(j).c 
print addr (i) 
print octal (ptr) 
print function (2) 


Array cross=sections may be displayed by specifying the upper and 
lower bound of the cross-section as follows: 


print array (135, 1) 


which would orint array(1,1), array(2,1), ..., array(5,1). More 
than one dimension may be iterateds; for instance a(1#2,1%2) would 
print, in order, a(l,t), a(i,2), a(2,1), a(2,2). 


let, 1 
let (<variable>i<cross section>} = <expression> 


Set the <variable> specified to the value of the <expression>. 
If the types are not the same, conversion will be performed 
according to the rules of PL/I. Array cross-sections may be 
used with the Same syntax as in print. Note that one may not 
assign one array cross~-section to another. . 


let var = 2 

let arrav (2, 3) = j 
let p -> a. b(11#2) «c 
let ptr = null 


+ | 
= 10b 


Warning: because of compiler optimization, the change may not 
have immediate effect in the program. 
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continue, ¢ 
continue 


Cause probe to return to its caller. If entered from command 
level, probe will return to command level. After a break, the 
user’s program will, in effect, be restarted. To abort a 
debugging session, the quit button must be used. 


call, cl 
Call <procedure>([<expression>[,<expression>]...]) 


Call the subroutine with the arguments given. If the procedure 
has descriptors giving the type of the arguments expected, the 
ones given will be converted. to the expected type; otherwise, 
they will be vassed as they are. The print request may be used 
to invoke a function, with the same sort of araument conversion 
taking place. Note: if the procedure has no arguments, a null 
argument list, "()", must be given. 


call sub ("abc", p -> p2 -—> bv, 250, addr(j)) 
call sub_noargs () | 
print function ("010"b) 
goto, go to, go, a 
goto <label> 


Cause an exit from orobe and a non-local qoto to the statement 
specified. 


goto label_var - transfer to value of label 
variable 

goto action (3) - transfer to label constant 

qoto 29 - transfer to statement on line 29 
of current pronram 

goto $110 - transfer to line labeled 110 in 


the fortran program 


NYarning: because of comoiler optimization, unpredictable results 
may occur. . 
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Direct one or n statements beginning with the current statement 
(i.e. the source vointer) to be printed. Note: only executable 
statements for which code has been oaenerated can be listed; 
however, if several statements are requested, intervening text 
such as comments and nonexecutable statements will be included 
in the output. . 


Rpasition, as 


position <label> 
nosition {(+t-)n 


Set the source pointer to the statement indicated or to plus or 
minus no executable statements relative to the current statement. 


position label - set the source otr to label: ... 

position action (3) - to action(3): ... 

position 2-14 - to statement on line 14 of file 2 
of the program 

position +2 - move forward 2 statements in the 
source 

position -5 - move back 5 statements 

find, £ 


find "<strina>". 


Search for an executable statement containina the characters in 
<strina> and if found, set the source pointer to that statement. 
The search bveains after the current statement and continues 
around the proaqram as in the editors edm and aqedx. Notes because 
of reorderins of statements by the compiler, which, among other 
things, moves subvrograms to the end, the search may not 
necessarilv find things in the same order as one would expect 
from a source listing of the proaranm. 


find "write (6,10)" - locate the statement in the 
oroaram 
find "str wal -~ locate str = "a4 


find "aqt2"3 list - locate and print the statement 
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Symbol Commands 
stack, sk 
stack ([Ci,Jn) (all) 

Trace the stack backward from the ith frame for n frames. If no 
limits are aqiven, the entire stack will be traced. The trace 
consists of a list of active procedures and block invocations 
(including quick blocks) beginning with the most recent. In 


addition to the name of the block, a frame or level number is 
given, as is the name of any conditions raised in the frame. 


stack ~ trace the whole stack 
stack 3 - trace the first three frames 
stack 3, 2 ~ trace th 3rd and 4th frames 


Normally, system or subsystem support procedures will not be 
included in the stack trace. If desired, thev may he included by 
specifying "all". 


stack all 
stack 3,5 all 


Use, U 
use [<block>] 


Selects a new block or procedure to be examined. If no <block> 
is agiven, then the block originally used when probe was entered 
will be assumed. The symbol pointer is set to the <block> 
specified so that variables in that block can be referenced. In 
addition, the source pointer is set to the last statement 
executed in the block? in this way, the point at which the block 
exited may be found with the help of the list command. 
Acceptable <block>s includes . 


<procedure> 
<label> 


Here <procedure> is the name of a procedure whose frame is 
desired$ its usaqe is essentially the same as if used on the 
command line. A <label> denotes the block containing the 
statement identified by the label or line number -— for instance, 
the label on a begin statement denotes that beain block. If the 
<label>s block is not active, the source pointer will be set to 
the statement specified. "level jij" will use the ith block frame 
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from a stack trace. "-<g" will use the nth previous instance of 
the current block allowing one to move back to a previous 
recursion level. (If more frames are requested than actuallv 
exist, tne last one found will be used.) 


use sub ~ use block procedure sub occupies 
use label ~ use block containina label: ... 
use level 2 - use second frame in stack trace 
use -| - use previous instance of current 
block 
use ~—999 - use first (oldest) instance 
symbal 


symbol <identifier> 


Display the-attributes of the variable specified and the name of 
the block in which its declaration is found. If the variable has 
variable size or dimensions, an attempt will be made to evaluate 
the size or extent expression; if the value is not available, 
then "*" will pe used instead. 


where, wh 
where Lsourceisymbol fcontrol] 


Display the current value of one or all of the pointers. Source 
and control will give the statement number of the corresponding 
statement. Symbol will give the name of the block currently 
being used3; if the block is active, its level number will also 
appear. 


where - give value of alli three pointers 
where source - give the value of the source 
pointer 
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Break Commands 
insert, i 
insert [<label>]: (<command>!(<command list>)} 


Set a breakpoint before the statement specified by <label> and 
cause the command(s) given to be associated with the break. If 
no <label> is given, the current statement will be assumed. When 
the running program arrives at the statement, probe will be 
entered before the statement is executed, and the commands will 
be processed automatically. When finished with the commands, 
probe will return, and the program will resume at the statement 
at which the break was set. In effect, the user may "insert" 
probe commands into his program. . 


insert: (print var3 print var2) 
~ set a break before the current 
| statement 
insert quick: orint x = set a break before the statement 
labeled quick : 


Note that the command list may extend across line boundaries if 
necessary. 


append, a 
append [<label>]: {<command>i(<command list>)} | 


is the same as insert except that the break is set after the 
statement designated. This means that the command list will be 
interpreted after the statement has been executed. If the 
statement branches to another location in the program, probe will 
not be entered. The difference between appending at one 
statement and inserting at the next is that a transfer to _ the 
next statement would cause a break for the insert case but would 
not for the anpend one. 


ston, sp 
stop 


Causes probe to stop processing its current input and read 
commands from the console. A new invocation of probe is created 
with new pointers set to the values at the time "stop" was 
executed. It is of primary use as part of a break command list 
as it enables the the user to enter commands while a program is 
suspended by a break. In effect, he may halt a running program. 
A subsequent continue command would cause probe to resume what it 
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was doing before stonping -<—- for instance, finish a break command 
list and return to the program. The command: 


insert 29% stop 


would cause the program to halt at statement 29 and allow the 
user to enter probe commands. Continue would restart the program. 
Similarly: 


append: (print a$ stops print b) 


would cause the value of a to be eieed before the program 
halteds later, after the user entered a "continue® command, the 
value of b would be printed, and the execution of the program 
resumed. 


reset, x 


reset 

reset (atiafteribefore} <label> 
reset <procedure> 

reset * 


Delete breaks set by the insert or append commands. Just "reset" 
deletes the last break that occurred} the <label> form deletes 
breaks set before and/or after a statement <procedure> and x" 
may be used to reset all the breaks in a segment, and all breaks 
in all segments, respectively. 


reset | - delete the current break 
reset at 34 - delete breaks inserted and 
appended at 34 
reset after 34 - delete the break appended after 
reset sub - delete all breaks in sub 
reset x ~ delete all breaks known 
Status, st 7 
status 


status (ak iarter instars) <label> 
status <procedure> 
status * 


Give information about what breaks have been set. The scope of 
the requests is similar to "reset": 


status - tist the current break 
status before label - list the break inserted at labels: 


i dle a 


: 
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status sub ~ tell what breaks have been set in 
sub 
status * - tell what procedures. have breaks 
. set in them 
pause, pa 
pause 


Equivalent to "stop$ reset® in a break command list, it causes 
the procedure to execute a break only once —. stopping, then 
reseting the break. | 


‘tap, 3 
step 

Set break consisting of "pause" after the statement following the 

control pointer and "continue". It enables the user to step 

through his program one statement at a time. Note: that if a 


statement transfers elsewhere, the break will not happen until 
sometime later, if ever. | 


i sl) e Cs 1 
"brief, b 

brief fonioff] 
Turn brief message mode on or off. In brief mode, most messages 
generated by probe will be much shorter and others will be 
surpressed altogether. The default is off . | 
execute, axec, &x 

execute “<string>" 


Pass <string> to the command processor to be executed as a normal 
Multics command. 
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Conditional Predicates 


if <conditional>: {<simple command>i(<command list>) } 
The command(s) will be executed if the <conditional> evaluates to 
true. The <conditional> may be of the form 
<expression><op><expression> with <=, <, =, *=, >, >= allowed as 
<Op>s. a 

if a < bs let p = addr (a) 


This predicate is of most use in a break command list as it can 
be used to cause a conditional stops 


insert: if z *= "10"bt stop 
would cause the program to stop only when z *= “10"b. 
while, wl | 
while <conditional>: (<simple command>i(<command list>))} 


Allows iteration by executing the command(s) as long as the 
<conditional> is true. 


while p *= nulls (print p =-> r.vals let p = p -> renext) 
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Expressions: 


Allowable <expression>s include simple scalar variables, 
constants, and probe builtin functions. The sum*tand difference 
of computational values can also be used. 


Variables may be simple identifiers, subscripted references, 
'- structure qualified references, and locator qualified references. 
Subscripts are also expressions. Locators must be offsets or 
pointer variables or constants. 


running_total 

salaries (p -> i = 2) 
aeb(2).c(3) or aeb.c(2,3) etc. 
Xey ~> var 


Arithmetic, string, bit, and pointer constants are 
supported. Arithmetic constants may be either decimal or binary, 
fixed or float, real or complex. Also, octal numbers are 


permitted as abbreviations for binary integers (e.a. 120 = 10). 
-123 45.37 | (2.1-0.31 
10b 4.73e10 123456700 


Character and hit strings without repetition factors are allowed. 
Character strings may include newline characters. Octal strings 
may be used in the place of bit strings (e.g. "23"0 = 
MOOIOTOOII"b). | | : | 


"abc" H1010"b 
"Nquote"#instring" "01234567"0 


Pointer constants are of the form? seg#iword#(bit#). The sea# 
and word# must be in octal. The bit# is optional and must be in 
decimal. They. may be used as locators. 


21435764 232174139) 


Three builtin functions are provided by probe: addr, null, . 
and octal. The addr function takes one argument and returns a 
pointer to that argument. Null, taking no arguments, returns a 
null pointer. They are the same as in PL/I. The function octal 
acts very much like PL/I’s unspec builtin in that it treats its 
argument as a bit string of the same lenath as the raw data 
~ value, and may be used in a similar manner as a psuedo-variable. 
However, when used in the print command the value is displayed in 
octal. (Data items not occupying a multiple of three bits will 
be padded on the right.) 
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A <label> identifies a source program statement and may be a 
label’ variable or constant, a line number as it appnears on a 
source listing (i.e. ([file-Jline), or a special statement 
‘designators $c representing the "current statement", $b 
reoresenting the statement on which the last break occurred, and 
Soumber for fortran labels. An optional offset of the form ",s" 
is also allowed. 


label - statement at label: ... 
label_var - statement that label._var is set 
$k to 
17 - statement on line 17 of program 
3-14,2 | - statement 2 on line 14 of file 3 
$b - statement at which last obvreak 
occurred 
Sc,l - statement after current statement 
$100 '- fortran statement labeled 100 
Procedure References: 


. A <procedure> is considered to be a reference to an entry 
variable or constant. External names may be used. 


Evaluation of Variable References: 


When a variable is referenced in a command, obrobe will 
attempt to evaluate it by first checking for an applicable 
declaration in the current block as indicated by the symbol 
pointer, and if necessary in its parents. If not found, the list 
of builtin functions will be searched. Finally, when the context 
allows a <procedure>, a search will be made following the user’s 
search rules. 


| The block in which to look for a variable may be altered by 
the use command which sets the symbol pointer. For example, if 
“print var" displays the value of var in the current block, then 
"use —-13 orint var" displays the value of var at the previous 
level of recursion. A shorthand is available for referencing 
variables in other blocks —— an optional block snecification: 


<variable> [<block>] 


where block is the same as in the use command. The use of 
<block>s in this manner does not alter the symbol pointer. 
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-var{-1] | - looks for previous value of var 
abcfother_block] - looks in “other_block" for abc 
xyz{39] ~ looks in block containina line 39 
nem€level 4] | - looks in block at level 4 
q(2)Csub} — - looks in procedure sub 


A block specification may be used on an identifier anywhere 
variable could be used. However, a block specification 
label or entry constant is ignored unless 1) the relative 
' format is used, and 2) the label or entry is itself used 
block specifcation. In Such a case, it is taken to mean the 


the 
on a 
(-n) 
in a 
oth 


previous instance of the block designated by the label or entry; 
that is, "var{sub[-2]]" references var in the second previous 


invocation (third on the stack) of sub. 
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nample Debugging Session: 


The following is a sample attempt at debuaging a program. 
It is not claimed that the program does anything useful, or that 
this is the best way to debug the program. The purpose is merely 
to give an example of now certain probe commands can be applied. 
A listing of the source of the program, test, is aiven on the 
next page$ the sample outout follows with ">" used to denote 
lines typed by the user. 


In order to use probe to debug a program, the program must 
be compiled with the "<table" option. Generally, the user should 
generate a symbol table for any program that he does not have 
good reason to believe will work. 


On line 5, the user calls his program;3 noticing that it 
seems to be looping, he _ stops it by hitting the quit button. 
After the user invokes probe, it responds by tellina that the 
internal function "fun" was executing line 38 when interrupted. 
Since the source pointer was automatically set to that line, a 
request to print the current statement with "list™, displays the 
source. The statement causing an error could be displayed in a 
similar manner. 


The stack command was’ then used to see what called what. 
The ouput shows that procedure "test" was called from command 
level, and then, in turn, called fun. While fun was executina, a 
quit occured and established a new command level. To determine 
whether fun was called from line 17 or line 27 of test, the use 
command is used to find the point at which test exited. Since 
"use" also sets the symbol pointer at the same time, the user can 
check if "s.num" has the correct value with the print command. 


The user decides that it would be worthwhile to trace the 
value of i. Rather than recompiling his program with a put 
statement added in a strategic location, probe allows him to set 
a break containina a print command to accomplish the same thing. 
Wanting to set the break after the do statement on line 16, the 
user searches for it with the find command. "list" is used to 
verify that the correct line was found. The continue command 
then causes probe to return (to command level). 


To abort the suspended program test, the user gives the 
release command to Multics. If he had done this just after 
quitting, he could not have used probe to find out much about 
what happened. 
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test: procedure$ 


declare 


(i, j) fixed binary, 
1 s structure based (bp), 
2 num fixed binary, 
2b (n refer (senum)) float binary, 
p pointer, n fixed cried 
sysprint file; 


nm = 53 


allocate s set (p)3 


do i= | to s.num3 

seb(i) = fun (i, 1)3 
end 3 
put skip list (s.b)3 


do j = s.num to | by -13 


seb(j) = fun (-j, -1)3 


ends 
put skip list(s.b)$3 


return 3 


-funs procedure (b, i) returns (float binary)3 


declare 
(b, 1) fixed binary3 


if b=0 
then return (1)$3 
else do3 
b=b -— i3 


return (2**kb + fun (b, i))3 
end} | 


end fun} 


44 end test3 
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The program is started once again, but now, after each time 
line 16 is executed, the break occurs and probe prints the value 
of i. Clearly, it is not being incremented as it should. Since 
this approach is not producing any useful information, the user 
aborts the program and trys to delete the break. The status 
command is used to tell what breaks have been set in the segment 
test, and then to see the break set. The break is then deleted 
with the reset command. Note that if there had also been a 
"Break before 16", then the command "reset at 16" would have 
deleted both. 


The user next decides to see what is going on in fun, so he 
sets a*break to halt it every time it is invoked. By looking at 
the listing, he knows that the first statement in fun is on line 
34, so he "positions" the source pointer to that statement and 
"inserts" a "stop". To accomplish the same thina, "insert 34: 
stop" could have been used. 


The program halts when the break before line 34 is reached. 
The user displays b and i getting the values he expected. The 
where command is also used to see what the state of things is. 
Continue ("c") restarts fun which calls itself recursively and 
stops again. The stack command (showing the last five frames) 
verifies that fact. The user prints the b in the current 
instance of fun (at level 2) and in the previous one (at level 
3). Mistakenly expecting the b’%s at different levels to be 
different, he gets suspicious. The variable "i" has the value 
expected, but the symbol command shows that it is wrong one -— 
the parameter to fun, not the loop index. To qet the correct 
one, he must look in the frame belonging to the procedure test. 
This "i" has been set to zero. The user then realizes his error. 
The function is modifying its argument (the loop index "i") on 
line 37. Done with debuaging the program, "reset" is used to 
delete the currently active break (the one that just occurred), 
and the program is aborted. 
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(quit) 


pli test -table > 
PL/I 
r 1248 3.211 28.336 280 


test : 


QUIT | | 
r 1250 5.371 6.702 52 level 2, 10 


probe 


Condition quit raised at line 38 of fun. 


list 


stack 
l command_processor_ 
2 release_stack 

3 unclaimed _sional 

4 real_sdh_ | 

5 return_to_ring_O_ 
6 fun | = 
a 

8 

9 
10 


test 
command_processor.__ 
listen. 
process_overseer_ 
11 real_init_admin_ 
use level 7 
list 


seb(i) = fun (i, 1)3 
print s.num 


5 
find "i = 1"3 list 

do i= 1 to senum$ 
append: print i 
continue 


r 1252 1.375 16.394 354 level 2, 10 


release 
r 1252 .126 .922 19 


test 


ee ae 


QUIT 
r 1252 3.069 .650 25 level 2, 12 


quit 


return (2**b + fun (b, i))3 
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49 > release 

50 r 1253 .9092 .937 20 

51 

52 > probe test 

53 > status test 

54 Break after line 16. 

55 > status after 16 

56 Break after line 16? print i 
57 > reset at 16 

58 Break reset after line 16 of test. 
59 > position 34 

60 > list 

ron] if b=0 

62 then return (1)3 
63 > insert: stop 

64 > continue 

65 r 1255 .781 12.356 333 

66 

67 > test 

68 Stopped before line 34 of fun. 
69 > print b 

70 1 

TI > where 

72 Current line is line 34 of test. 
T3 Using level 2: fun. 

74 Control at line 34 of fun. 

715 > print i 

76 1 

77 SC 

78 Stonped before line 34 of fun. 
719 > stack 5 

80 | break 

81 2 fun 

82 3 fun 

83 4 test 

84 5 command processor. 

~B5 > print b 

86 @) 

87 > print b[-1] 

88 0 

89 > print i 

90 1 

91 > symbol i | 
92 Attributes ares fixed binary(17,0) aligned parameter. 
93 Declared ins fun. 

94 > use test 


95 > print i 
6) 
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97 
98 
99 
190 
101 
102 
103 
104 


> reset 
Break reset before line 34 of test. 
(quit) 
QUIT . 
r 1307 4.870 64.788 1544 level 2, 18 


> release 
r 1307 .076 .992 31 


